<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Optional Generator (-a)</title>
<link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../../index.html" title="Spirit 2.59">
<link rel="up" href="../operator.html" title="Generator Operators">
<link rel="prev" href="list.html" title="List Generator (a % b)">
<link rel="next" href="and_predicate.html" title="And-Predicate Generator (&amp;a)">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="list.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../operator.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="and_predicate.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="spirit.karma.reference.operator.optional"></a><a class="link" href="optional.html" title="Optional Generator (-a)">Optional
          Generator (<code class="computeroutput"><span class="special">-</span><span class="identifier">a</span></code>)</a>
</h5></div></div></div>
<h6>
<a name="spirit.karma.reference.operator.optional.h0"></a>
            <span class="phrase"><a name="spirit.karma.reference.operator.optional.description"></a></span><a class="link" href="optional.html#spirit.karma.reference.operator.optional.description">Description</a>
          </h6>
<p>
            The optional generator is used to conditionally execute an embedded generator.
            It succeeds always.
          </p>
<h6>
<a name="spirit.karma.reference.operator.optional.h1"></a>
            <span class="phrase"><a name="spirit.karma.reference.operator.optional.header"></a></span><a class="link" href="optional.html#spirit.karma.reference.operator.optional.header">Header</a>
          </h6>
<pre class="programlisting"><span class="comment">// forwards to &lt;boost/spirit/home/karma/operator/optional.hpp&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma_optional</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
</pre>
<p>
            Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>.
          </p>
<h6>
<a name="spirit.karma.reference.operator.optional.h2"></a>
            <span class="phrase"><a name="spirit.karma.reference.operator.optional.model_of"></a></span><a class="link" href="optional.html#spirit.karma.reference.operator.optional.model_of">Model of</a>
          </h6>
<div class="blockquote"><blockquote class="blockquote"><p>
              <a class="link" href="../generator_concepts/unarygenerator.html" title="UnaryGenerator"><code class="computeroutput"><span class="identifier">UnaryGenerator</span></code></a>
            </p></blockquote></div>
<h6>
<a name="spirit.karma.reference.operator.optional.h3"></a>
            <span class="phrase"><a name="spirit.karma.reference.operator.optional.expression_semantics"></a></span><a class="link" href="optional.html#spirit.karma.reference.operator.optional.expression_semantics">Expression
            Semantics</a>
          </h6>
<p>
            Semantics of an expression is defined only where it differs from, or
            is not defined in <a class="link" href="../generator_concepts/unarygenerator.html" title="UnaryGenerator"><code class="computeroutput"><span class="identifier">UnaryGenerator</span></code></a>.
          </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Expression
                    </p>
                  </th>
<th>
                    <p>
                      Semantics
                    </p>
                  </th>
</tr></thead>
<tbody><tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="special">-</span><span class="identifier">a</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      The generator <code class="computeroutput"><span class="identifier">a</span></code>
                      is executed depending on the availability of an attribute.
                      The optional generator succeeds if its embedded generator succeeds
                      (unless the underlying output stream reports an error).
                    </p>
                  </td>
</tr></tbody>
</table></div>
<h6>
<a name="spirit.karma.reference.operator.optional.h4"></a>
            <span class="phrase"><a name="spirit.karma.reference.operator.optional.attributes"></a></span><a class="link" href="optional.html#spirit.karma.reference.operator.optional.attributes">Attributes</a>
          </h6>
<p>
            See <a class="link" href="../../quick_reference/compound_attribute_rules.html#spirit.karma.quick_reference.compound_attribute_rules.notation">Compound
            Attribute Notation</a>.
          </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Expression
                    </p>
                  </th>
<th>
                    <p>
                      Attribute
                    </p>
                  </th>
</tr></thead>
<tbody><tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="special">-</span><span class="identifier">a</span></code>
                      (optional, unary <code class="computeroutput"><span class="special">-</span></code>)
                    </p>
                  </td>
<td>
                    <p>
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="special">-</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">-</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></pre>
<p>
                    </p>
                  </td>
</tr></tbody>
</table></div>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
              The table above uses <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></code> as a placeholder only. The notation
              of <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></code>
              stands for the data type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></code>.
            </p></td></tr>
</table></div>
<p>
            The optional generator will execute its embedded generator once if the
            provided attribute holds a valid value. It forwards the value held in
            its attribute to the embedded generator.
          </p>
<p>
            It is important to note, that the optional generator does not perform
            any buffering of the output generated by its embedded elements. That
            means that any failing element might have already generated some output,
            which is <span class="emphasis"><em>not</em></span> rolled back.
          </p>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top">
<p>
              The simplest way to force a optional generator to behave as if it did
              buffering is to wrap it into a buffering directive (see <a class="link" href="../directive/buffer.html" title="Generator Directive for Temporary Output Buffering (buffer[])"><code class="computeroutput"><span class="identifier">buffer</span></code></a>):
            </p>
<p>
</p>
<pre class="programlisting"><span class="identifier">buffer</span><span class="special">[-</span><span class="identifier">a</span><span class="special">]</span></pre>
<p>
            </p>
<p>
              which will <span class="emphasis"><em>not</em></span> generate any output in case of
              a failing generator <code class="computeroutput"><span class="special">-</span><span class="identifier">a</span></code>.
            </p>
</td></tr>
</table></div>
<h6>
<a name="spirit.karma.reference.operator.optional.h5"></a>
            <span class="phrase"><a name="spirit.karma.reference.operator.optional.complexity"></a></span><a class="link" href="optional.html#spirit.karma.reference.operator.optional.complexity">Complexity</a>
          </h6>
<div class="blockquote"><blockquote class="blockquote"><p>
              The overall complexity of the optional generator is defined by the
              complexity of its embedded generator. The complexity of the optional
              generator itself is O(1).
            </p></blockquote></div>
<h6>
<a name="spirit.karma.reference.operator.optional.h6"></a>
            <span class="phrase"><a name="spirit.karma.reference.operator.optional.example"></a></span><a class="link" href="optional.html#spirit.karma.reference.operator.optional.example">Example</a>
          </h6>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
              The test harness for the example(s) below is presented in the <a class="link" href="../basics.html#spirit.karma.reference.basics.examples">Basics Examples</a>
              section.
            </p></td></tr>
</table></div>
<p>
            Some includes:
          </p>
<p>
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">support_utree</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">phoenix</span><span class="special">/</span><span class="identifier">core</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">phoenix</span><span class="special">/</span><span class="keyword">operator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fusion</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">std_pair</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">proto</span><span class="special">/</span><span class="identifier">deep_copy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
</pre>
<p>
          </p>
<p>
            Some using declarations:
          </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">double_</span><span class="special">;</span>
</pre>
<p>
          </p>
<p>
            Basic usage of an optional generator:
          </p>
<p>
</p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">val</span><span class="special">(</span><span class="number">1.0</span><span class="special">);</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"1.0"</span><span class="special">,</span> <span class="special">-</span><span class="identifier">double_</span><span class="special">,</span> <span class="identifier">val</span><span class="special">);</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"2.0"</span><span class="special">,</span> <span class="special">-</span><span class="identifier">double_</span><span class="special">,</span> <span class="number">2.0</span><span class="special">);</span>
</pre>
<p>
          </p>
<p>
            Usage and result of an empty optional generator:
          </p>
<p>
</p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">val</span><span class="special">;</span>          <span class="comment">// empty optional</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">""</span><span class="special">,</span> <span class="special">-</span><span class="identifier">double_</span><span class="special">,</span> <span class="identifier">val</span><span class="special">);</span>
</pre>
<p>
          </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="list.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../operator.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="and_predicate.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
